Skip to content

docs: document render-plan DNS resolution - #163

Open
sylvesterkaczmarek wants to merge 1 commit into
openai:mainfrom
sylvesterkaczmarek:docs/render-plan-dns-resolution
Open

docs: document render-plan DNS resolution#163
sylvesterkaczmarek wants to merge 1 commit into
openai:mainfrom
sylvesterkaczmarek:docs/render-plan-dns-resolution

Conversation

@sylvesterkaczmarek

Copy link
Copy Markdown
Contributor

Summary

Document that fence render-plan can perform DNS lookups when the policy contains exact hostname allowlist entries.

Problem

The CLI reference currently says render-plan validates JSON and prints firewall rules without applying them. That correctly describes host mutation, but it omits a separate observable side effect: the planner resolves exact hostname entries while building the frozen plan.

A user can therefore run a preview expecting a purely local operation and still generate DNS traffic or receive a DNS-resolution failure.

Evidence / reproduction

  • src/cli.rs::render_plan calls build_plan(normalized, resolver), and the system CLI supplies SystemResolver.
  • The plan builder resolves exact hostname allowances before rendering their effective IP allowances; this is how the preview freezes hostname policy into concrete addresses.
  • Existing CLI tests already exercise the failure path: a resolver failure while previewing a hostname policy produces dns_resolution_failed.
  • Minimal reproduction on a normal host: use a render-plan config containing an exact hostname and make system DNS unavailable. The command fails during planning even though it never applies nftables state.
  • IP- and CIDR-only preview policies do not require this hostname-resolution step.

The distinction matters for offline or tightly controlled development environments: render-plan is non-mutating with respect to Fence enforcement, but hostname-based previews are not necessarily network-free.

Change

Add one sentence to the CLI reference stating that exact hostname entries are resolved through the system resolver during planning and that DNS failure can fail the preview.

Documentation only; no planner, resolver, or firewall behavior changes.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant